home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Tool Chest / Development Tools & Languages / Macintosh Common Lisp Related / User Contributions / dm Folder.sea / dm Folder / dm.text < prev    next >
Encoding:
Text File  |  1993-02-11  |  12.3 KB  |  265 lines  |  [TEXT/CCL2]
  1.  
  2.  
  3.                             THE DUNGEON MASTER
  4.  
  5.                        AN ALTERNATIVE MODULE SYSTEM
  6.  
  7.  
  8.  
  9.                                 Sue Felshin
  10.            Laboratory for Advanced Technology in the Humanities
  11.  
  12.        Copyright (c) 1993 Massachusetts Institute of Technology
  13.    Permission is granted to distribute this document, provided that this
  14. copyright notice is retained intact.  This document is covered by the Free
  15.  Software Foundation GNU General Public License, Version 1, February 1989.
  16.  
  17.  
  18.  
  19.    The Dungeon Master (or DM) is a set of routines that simplifies the
  20. loading and compilation of large programs.  The DM works in terms of
  21. modules, which correspond roughly to files.  For each module, the DM
  22. records when it was last loaded, what other modules it depends on, and
  23. other information.  The DM assures that modules are loaded and compiled
  24. when necessary and in the correct order.  In a large system, file
  25. dependencies are complex and frequently circular.  Modules can request that
  26. other modules be loaded, but, in order to prevent infinite loops, the DM
  27. will not in general load any module already in the process of being
  28. loaded.(There are exceptions to this rule that vary from implementation to
  29. implementation of Common Lisp.  The DM is parameterized to know about the
  30. exceptions in various dialects of Common Lisp.)
  31.    The DM is an extension of the module system described in Section 11.8 of
  32. Common Lisp: the Language, but is incompatible with that system to the
  33. extent that it requires a one-to-one correspondence between modules and
  34. files.
  35.    This document describes how to use the DM within modules and
  36. interactively.
  37.  
  38.  
  39.  
  40. 1. Initialization Routines
  41.  
  42.  
  43. push-module-search-path name                                     [Function]
  44.  
  45.    The directory name is added to the front of the module search path.  Do
  46. not forget to add a trailing directory separator to name if your operating
  47. system requires it to construct the pathname.
  48.  
  49.  
  50.                               Copyright (C)
  51. 2. Module to Module Interface
  52.  
  53.    Use these routines in modules; that is, in source code.  Functions in
  54. the next section are handier for using the Dungeon Master interactively.
  55.  
  56.  
  57. provide-module name &key (compile t) (documentation nil)            [Macro]
  58.  
  59.    Name may be a string or a symbol.  If a symbol, the name of the module
  60. will be the print name of the symbol.  Symbols are generally more
  61. convenient to use than strings, and in order to prevent package conflicts,
  62. it is a convention to give all module names as keywords.
  63.    If compile is nil, the module will never be compiled by any DM function.
  64. This may be appropriate for some data files.  Documentation specifies a
  65. documentation string to be associated with the module.
  66.    A provide-module statement should appear at the top of each module,
  67. immediately below the call to in-package.  This statement declares the name
  68. of the module.  It is an error for a file to contain more than one
  69. provide-module statement.  If a file is treated as a module, but contains
  70. no call to provide-module, a continuable error is signalled.
  71.    When a module finishes loading, it is marked as successfully loaded and
  72. the DM remembers such information as what file the module was loaded from,
  73. the time at which it was loaded, and whether or not a compiled version was
  74. loaded.  The DM also remembers all of the modules dependencies, based on
  75. the calls to require-module contained directly within the module; this list
  76. is reset when a module is reloaded, so that it is always accurate.
  77.  
  78.  
  79. require-module module &key path (eval :load) (load :load)           [Macro]
  80.                            (compile :load) (when t)
  81.                            (macros nil) (inlines nil)
  82.                            (accessors nil) (modifiers nil)
  83.                            (constructors nil) (includes nil)
  84.                            (classes nil) (specializers nil)
  85.                            (read-macros nil)
  86.                            (toplevel-calls nil)
  87.  
  88.    Require-module ensures that definitions in another module are available
  89. to the current module.  Typically this involves loading (and possibly
  90. compiling) the other module, but this is not always necessary.  The DM
  91. determines what action needs to be taken based on the keyword arguments to
  92. require-module.
  93.  
  94.  
  95.      path      Require-module finds a file to load by checking the
  96.                search path for a file with the same name as the module
  97.                (adjusted to fit the file naming standards of the
  98.                operating system).  Use this keyword to override the
  99.                module name, bypass the search path, or otherwise
  100.                change what path is used to find the module's file.
  101.      eval, load, and compile
  102.                It is possible, though not common, for a required
  103.                module not to be required under certain circumstances.
  104.                For instance, a file containing only data may be
  105.                required to run code in a module, but not to compile
  106.                it.(Note that if the "data" file exports symbols or
  107.                proclaims the types of variables, then it is not a
  108.                "pure" data file and is required for compilation.)  A
  109.                file containing reader macros may be required to eval
  110.                or compile a file, but not to load it.  If the required
  111.                module is not required under one of these
  112.                circumstances, set the corresponding argument to nil.
  113.      when      If this argument is provided and evaluates to nil, then
  114.                the require-module form will be ignored.  In a large
  115.                system with many subsystems, one module might only
  116.                require another module when a certain subsystem is
  117.                being loaded.
  118.      macros    If the current module calls any macros in the required
  119.                module, then this argument should be t.
  120.      inlines   If the current module calls any functions in the
  121.                required module which have been proclaimed or declared
  122.                inline, then this argument should be t.(If you are
  123.                running Lucid Common Lisp 01.01.0000 on the IBM RT
  124.                running AIX Release 1.2 Version 2, be warned that due
  125.                to a bug, it is necessary to set this argument to t if
  126.                the function is proclaimed inline, even if it is
  127.                locally declared notinline.)
  128.      accessors If the current module calls any structure accessor
  129.                functions defined in the required module, this argument
  130.                should be t.
  131.      modifiers If the current module performs any setfs on structure
  132.                accessors defined in the required module, this argument
  133.                should be t.
  134.      constructors
  135.                If the current module calls any structure constructor
  136.                functions defined in the required module, this argument
  137.                should be t.
  138.      includes  If the current module includes any structures defined
  139.                in the required module, this argument should be t.
  140.      classes   If the current module defines classes based on classes
  141.                defined in the required module, this argument should be
  142.                t.
  143.      specializers
  144.                If the current module defines methods whose
  145.                specializers include types (classes or other types)
  146.                defined in the required module, this argument should be
  147.                t.
  148.      read-macros
  149.                If the current module uses any reader macros defined in
  150.                the required module, this argument should be t.
  151.      toplevel-calls
  152.                If the current module makes toplevel calls to
  153.                functions, macros, or variables defined in the required
  154.                module, this argument should be t.
  155.  
  156.  
  157.    If the DM decides that the required module needs to be loaded, it calls
  158. find-module-file with module and path to determine the file to load.
  159.  
  160.  
  161. mload-protect &body body                                            [Macro]
  162.  
  163.    Executes body when the current module is done loading or compiling, even
  164. if there is an abnormal exit before loading or compilation is complete.
  165. This is typically used to ensure that temporary reader macros are removed
  166. from the Lisp environment.
  167.  
  168.  
  169.  
  170. 3. Interactive Interface
  171.  
  172.    These routines may be used from the Lisp Listener.  It is tasteless to
  173. use them in source code.
  174.  
  175.  
  176. unprovide-module module                                          [Function]
  177.  
  178.    Module may be a string or symbol, as for provide-module.  The DM deletes
  179. all its information about module and pretends it has never been loaded.
  180. Use this when you remove a module from your system, or misspell a module's
  181. name when referring to it, to prevent load-modules or compile-modules from
  182. attempting to load or compile the defunct module.
  183.  
  184.  
  185. mload module &key path (compile nil) (force t) (print nil)       [Function]
  186.                   (verbose *mload-verbose*)
  187.  
  188.    Loads a module.  If compile is true, mload first calls mcomp with :force
  189. nil to compile the module; then it loads module.
  190.    If force is nil, then the module is only loaded if it has never been
  191. loaded or has been changed since the last time it was loaded.  Path is used
  192. by find-module-file (see below) to determine the pathname of the module.
  193. Print and verbose are passed to load.
  194.  
  195.  
  196. mcomp module &key path (force t) (load t) (print nil)            [Function]
  197.                   (verbose *mload-verbose*)
  198.  
  199.    Compiles a module and, if load is t, loads the result.
  200.    If force is nil, the module is only compiled if the lisp file has been
  201. changed   Path is  sed by  ind module fi e to
  202. module.. Print anduverbosefare-passed-tolload.determine the pathname of the
  203.    Note that mcomp will refuse to compile a module that has :compile nil in
  204. its provide-module statement.
  205.  
  206.  
  207. load-modules &key (include nil) (exclude nil) (compile nil)      [Function]
  208.                   (force nil) (print nil)
  209.                   (verbose *load-verbose*) (query nil)
  210.  
  211.    Calls mload on the all the modules given in include except for those
  212. given in exclude.  If include is nil, then a list of all existing modules
  213. will be used as the include argument.  If query is t, then for each module
  214. that needs loading, you will be prompted as to whether you want to load the
  215. module.  Other arguments are passed through to mload.
  216.  
  217.  
  218. compile-modules &key (include nil) (exclude nil) (load t)        [Function]
  219.                      (force nil) (print nil)
  220.                      (verbose *load-verbose*) (query nil)
  221.  
  222.    Calls mcomp on the all the modules given in include except for those
  223. given in exclude.  If include is nil, then a list of all existing modules
  224. will be used as the include argument.  If query is t, then for each module
  225. that needs compiling, you will be prompted as to whether you want to
  226. compile the module.  Other arguments are passed through to mcomp.
  227.  
  228.  
  229. uncompiled-modules                                               [Function]
  230.  
  231.    Returns a list of all modules which are uncompiled in the current lisp
  232. environment.  It can be used as the include argument to compile-modules on
  233. machines where file access is slow.  It can also be used to obtain a list
  234. of suspects for why your code might be running slower than usual.  Modules
  235. in this list may not actually need compilation; it may just be that the
  236. compiled versions aren't loaded.
  237.  
  238.  
  239. modules-dependent-on &rest modules                               [Function]
  240.  
  241.    Returns a list of all modules which depend on any of modules, a list of
  242. modules and/or module names.  Use this function to pass a list of modules
  243. to compile to compile-modules when you want to (re)compile only those
  244. modules that depend on, say, a single module you just changed, without
  245. compiling all modules that might need it.
  246.  
  247.  
  248. search-for-file file &optional                                   [Function]
  249.                    (search-path *module-search-path*)
  250.  
  251.    Searches for file in each directory on search-path.  If file does not
  252. specify a file type, then both lisp and binary files are tried, and the one
  253. with the most recent write-date is returned.
  254.  
  255.  
  256. find-module-file module &optional file lsp-only                  [Function]
  257.  
  258.    Finds the pathname of the file from which module should be loaded.  If
  259. file does not contain a name, then the module name (converted to a file
  260. name as appropriate for the current configuration) is used.  If lsp-only is
  261. t, then only lisp source files will be returned, not compiled binary files.
  262. Find-module-file uses search-for-file.
  263.    The functions mload, mcomp, and require-module all call find-module-file
  264. to translate module names into pathnames.
  265.